<HTML>

<HEAD>

<TITLE>tclOSAScript -- OSA</TITLE>

</HEAD>

<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF0000" ALINK="#00FF00">

<H2 ALIGN="CENTER">TclAppleScript Extension Command</H2>

<H3>NAME</H3>
<DL>
<DT>
AppleScript - Communicate with the AppleScript OSA component to run
	AppleScripts from Tcl.
</DL>
<H3>SYNOPSIS</H3>
<DL><DT>
<B>AppleScript <A NAME="compile">compile</A> </B><I>?-flag value?</I> <I>scriptData1 
	   ?ScriptData2 ...?</I><I>componentName</I>
<BR>
<B>AppleScript <A NAME="decompile">decompile</A></B> <I>scriptName</I>
<BR>
<B>AppleScript delete </B><I>scriptName</I>
<BR>
<B>AppleScript <A NAME="execute">execute</A> </B><I>?flags value?</I> <I>scriptData1 
	?scriptData2 ...?</I>
<BR>
<B>AppleScript <A NAME="info">info</A> </B><I>what</I>
<BR>
<B>AppleScript <A NAME="load">load</A></B> <I>?flag value? fileName</I>
<BR>
<B>AppleScript <A NAME="run">run</A></B> <I>?flag value?</I>
		    <I>scriptName</I>
<BR>
<B>AppleScript <A NAME="store">store</A></B> <I>?flag value? scriptName fileName</I>
<BR>
</DL>

<H3>DESCRIPTION</H3>
<DL>
<DT>


This command is used to communicate with the AppleScript OSA component.  
You can <A HREF="#compile"><B>compile</B></A> scripts, <A 
HREF="#run"><B>run</B></A> compiled scripts, <A 
HREF="#execute"><B>execute</B></A> script data (i.e.  compile and run at a 
blow).  You can get script data from a compiled script (<A 
HREF="#decompile"><B>decompile</B></A> it), and you can <A 
HREF="#load"><B>load</B></A> a compiled script from the scpt resource of a 
file, or <A HREF="store"><B>store</B></A> one to a scpt resource.  You can 
also get <A HREF="#info"><B>info</B></A> on the currently available scripts 
and contexts.  It has the general form

<DL>
<DT>
<P>
<I>AppleScript option ?arg arg ...?</I>
<P>
</DL>
The possible sub-commands are:
<P>
<DL>
	<DT>
	<I>AppleScript</I> <A NAME="compile"><B>compile</A> </B><I>?-flag value?</I> <I>scriptData1 
	   ?ScriptData2 ...?</I>
	<BR>
	
	<DD>
        The scriptData 
	elements are concatenated (with a space between each), and
	sent to AppleScript
        for compilation.  There is no limitation on the size of 
	the scriptData, beyond the available memory of the Wish interpreter.  
	<P>
	If the compilation is successful, then the command will return a token 
	that you can pass to the <A HREF="#run">"run"</A> subcommand.  If the 
	compilation fails, then the return value will be the error message from 
	AppleScript, and the pertinent line of code, with an "_" to indicate 
	the place where it thinks the error occured.
	<P>
	The 
	compilation is controlled by flag value pairs.  The available flags 
	are:
	<P>
	<DL>
		<DT>
		<A NAME="first compile switch"><B>-augment Boolean</B></A>
		<DD>
		To be used in concert with the <A HREF="#-context">-context</A> flag.  
		If augment is yes, 
		then the scriptData augments the handlers and data already in the 
		script context.  If augment is no, then the scriptData replaces the 
		data and handlers already in the context.  The default is yes.  
		<P>		
		<!-- I'm leaving this flag out for now, since I can't seem to get the
		     AE manager to obey it.  Even when I hard code the value, applications
		     still switch to the foreground.  Oh, well...
		     
		<DT>
		<B>-canswitch Boolean  </B>
		<DD>
		 If yes, then applications activated by the code in scriptData will 
		 be allowed to switch to the foreground.  If no, then they will use 
		 the notification manager to indicate they need attention (this 
		 usually means they blink the Finder icon, and put a check in the 
		 application's entry in the Finder menu). 
		 -->
		 
		<DT>
		<B><A NAME="-context">-context</A> Boolean</B>
		<DD> 
		This flag causes the code given in the scriptData to be compiled 
		into a "context".  In AppleScript, this is the equivalent of creating an Tcl 
		Namespace.  The command in this case returns the name of the context as 
		the its result, rather than a compiled script name.
		<P>
		You can store data and procedures (aka 
		handlers) in a script context.  Then later, you can 
		run other scripts in this context, and they will see all the data and 
		handlers that were set up with this command.  You do this by passing the
		name of this context to the -context flag of the run or execute subcommands.
		<P>
		Unlike the straight compile command, the code compiled into a 
		script context is run immediatly, when it is compiled, to set up the context.
		<DT>
		<P>
		<B>-name string</B> 
		<DD>
		Use <I>string</I> as the name of the script or script context.  If there is 
		already a script 
		of this name, it will be discarded.  The same is true with script 
		contexts, unless the <I>-augment</I> flag is true.  If no name is provided, then a 
		unique name will be created for you.
		<DT>
		<P>
		<B>-parent contextName  </B>
		<DD>
		This flag is also to be used in conjunction with the <A HREF="#-context">-context</A> flag.  
		<I>contextName</I> must be the name of a compiled script context.  Then 
		the new script context will inherit the data and handlers from the 
		parent context.
	</DL>
	<P>
	<DT>
	<I>AppleScript</I> <B><A NAME="decompile">decompile</A></B> <I>scriptName</I>
	<BR>
	<DD>
	This decompiles the script data compiled into the script scriptName,
	and returns the source code. 
	<P>
	<DT>
	<I>AppleScript</I> <B>delete </B><I>scriptName</I>
	<BR>
	<DD>
	This deletes the script data compiled into the script scriptName,
	and frees up all the resources associated with it. 
	<P>
	<DT>
	<I>AppleScript</I> <B><A NAME="execute">execute</A> </B><I>?flags value?</I> <I>scriptData1 
	?scriptData2 ...?</I>
	<BR>
	<DD>
	This compiles and runs the script in scriptData (concatenating first), and 
	returns the results of the script execution.  It is the same as doing 
	<I>compile</I> and then <I>run</I>, except that the compiled script is 
	immediately discarded.
   <P>
	<DT>
	<I>AppleScript</I> <B><A NAME="info">info</A> </B><I>what</I>
	<DD>
	This gives info on the connection.  The allowed values for "what" are:
	<P>
	<DL>
	    <DT>
		<P>
	    <B>contexts </B> <I>?pattern?</I>
	    <DD>
	    This gives the list of the script contexts that have been.
            If <I>pattern</I> is given, it only reports the contexts 
	    that match this pattern.
	    <DT>
	<!--	<P>
	    <B>language</B>
	    <DD>
	    Returns the language of this OSA component
	    <DT>
        -->
		<P>
	    <B>scripts</B> <I>?pattern?</I>
	    <DD>
	    This returns a list of the scripts that have been compiled in the 
	    current connection.  If <I>pattern</I> is given, it only reports the 
	    script names that match this pattern.
	</DL>
	<P>
	<DT>
	<I>AppleScript</I> <B><A NAME="load">load</A></B> <I>?flag value? fileName</I>
	<DD>
	This loads compiled script data from a resource of type 'scpt' in the 
	file fileName, and returns a token for the script data.  As with the 
	<I>compile</I> command, the script is not actually executed.  Note that all 
	scripts compiled with Apple's "Script Editor" are stored as script
	contexts.  However, unlike with the "<I>compile -context</I>" command, the <I>load</I> 
	command does not run these scripts automatically.  If you want to set up 
	the handlers contained in the loaded script, you must run it manually. 
	<P>
	<I>load</I> takes the following flags:
	<P>
	<DL>
	    <DT>
	    <B>-rsrcname string</B>
	    <DD>
	    load a named resource of type 'scpt' using the rsrcname 
	    flag.
	    <DT>
		<P>
	    <B>-rsrcid integer</B>
	    <DD>
	    load a resource by number with the rsrcid flag.  
	</DL>
	<DD>
	<P>
	If neither the <I>rsrcname</I> nor the <I>rsrcid</I> flag is provided, then the load 
	command defaults to -rsrcid = 128.  This is the resource in which 
	Apple's Script Editor puts the script data when it writes out a 
	compiled script.
	<P>
	<DT>
	<I>AppleScript</I> <B><A NAME="run">run</A></B> <I>?flag value?</I> <I>scriptName</I>
	<DD>
	This runs the script which was previously compiled into <I>scriptName</I>.  If the script  
	runs successfully, the command returns the return value for this command, 
	coerced to a text string.  
	If there is an error in 
	the script execution, then it returns the error result from the 
	scripting component.  It accepts the following flag:
   
   <DL>
        <DT>
		<P>
		<B>-context contextName</B>
		<DD> 
		<I>contextName</I> must be a context created by a previous call to <I>compile</I> with 
		the -<I>context</I> flag set.  This flag causes the code given in the 
		<I>scriptData</I> to be run in this "context".  It will see all the data and 
		handlers that were set up previously.
   <!-- <DT>
		<B>-canswitch Boolean  </B>
		<DD>
		If yes, then applications activated by the code 
		in scriptData will be allowed to switch to the foreground.  If no, then 
		they will use the notification manager to indicate they need attention 
		(this usually means they blink the Finder icon, and put a check in the 
		application's entry in the Finder menu). -->		 
   </DL>
   <P>
	<DT>
	<I>AppleScript </I> <B> <A NAME="store">store</A></B> <I>?flag value? scriptName fileName</I>
	<DD>
	This stores a compiled script or script context into a resource of type 'scpt' in the 
	file fileName.  
	<P>
	store takes the following flags:
	<P>
	<DL>
	    <DT>
	    <B>-rsrcname string</B>
	    <DD>
	    store to a named resource of type 'scpt' using the rsrcname 
	    flag.
	    <DT>
		<P>
	    <B>-rsrcid integer</B>
	    <DD>
	    store to a numbered resource with the rsrcid flag.  
	</DL>
	<P>
	<DD>
	If neither the rsrcname nor the rsrcid flag is provided, then the load 
	command defaults to -rsrcid = 128.  Apple's Script Editor can read in files written by 
	tclOSAScript with this setting of the <I>-rsrcid</I> flag.
</DL>
</DL>
<H2>Notes:</H2>

The AppleScript command is a stopgap command to fill the place of exec
    on the Mac.  It is not a supported command, and will likely change
    as we broaden it to allow communication with other OSA languages.
<H2>See Also:</H2>


</BODY>

</HTML>
